Sprite 1984 - 1993/Sprite 1984 - 1993.iso/src/cmds/migrate/RCS/migrate.man,v

Text File | 1991-04-03 | 11.1 KB | 404 lines

head     1.8;
branch   ;
access   ;
symbols  ;
locks    ; strict;
comment  @@;


1.8
date     91.04.03.12.20.01;  author kupfer;  state Exp;
branches ;
next     1.7;

1.7
date     90.09.24.14.38.29;  author douglis;  state Exp;
branches ;
next     1.6;

1.6
date     90.02.20.18.27.55;  author douglis;  state Exp;
branches ;
next     1.5;

1.5
date     89.06.15.22.55.52;  author douglis;  state Exp;
branches ;
next     1.4;

1.4
date     89.05.04.17.01.10;  author douglis;  state Exp;
branches ;
next     1.3;

1.3
date     88.12.30.09.46.52;  author ouster;  state Exp;
branches ;
next     1.2;

1.2
date     88.12.22.09.56.27;  author ouster;  state Exp;
branches ;
next     1.1;

1.1
date     88.11.21.13.29.02;  author douglis;  state Exp;
branches ;
next     ;


desc
@manual page for migrate (formerly mig) command.
@



1.8
log
@Change "mig" to "migrate".
@
text
@' $Header: /sprite/src/cmds/migrate/RCS/migrate.man,v 1.7 90/09/24 14:38:29 douglis Exp Locker: kupfer $ SPRITE (Berkeley)
.so \*(]ltmac.sprite
.HS MIGRATE cmds
.BS
.SH NAME
migrate \- Migrate a command to another machine
.SH SYNOPSIS
\fBmigrate\fR [\fB\-BbvlD\fR] [[\fB\-h \fIhost\fR] | [\fB\-H \fIhostID\fR]] [\fB\-p \fIprocessID\fR] [(\fB\-E \fIcmd\fR arg0 | \fIcmd\fR) \fIargs ...\fR]
.BE
.SH INTRODUCTION
This command is used to execute commands remotely using the Sprite process
migration facility.  It may be used to execute commands on a
particular machine or to select from idle machines; and it may execute
a command specified by the arguments to the \fBmigrate\fR program, or an
interactive shell.
.SH "SELECTING A HOST"
.IP "\fB\-B\fR"
The \fB\-B\fR specifies that the host should be selected at
``background'' priority, rather than at the priority used for other
tasks such as compilations.
.IP "\fB\-h\fR"
.IP "\fB\-H\fR"
By default, a host is selected from among the idle hosts
available on the local network.  This host is then marked as being in
use for the duration of the command being executed; the host will not
be chosen for remote execution of other processes in the meantime.  If
a host is specified with the \fB\-h\fR or \fB\-H\fR options, then the
``in-use'' flag
is bypassed; this is useful when invoking \fBmigrate\fR as a ``remote
login'' facility to execute commands directly on another host.   The
\fB\-h\fR flag specifies a host by name, and the \fB\-H\fR flag
specifies it by spriteID (thereby bypassing the host database lookup
to convert from name to internal numeric identifier).
.IP "\fB\-l\fR"
If no host is specified and no idle host is available, the
command is not executed unless the \fB\-l\fR option is specified, in
which case the command is executed locally.   The ``\fB\-l\fR'' option similiarly
affects the disposition of the command if migrating to the other host fails.
.SH "EXECUTING A COMMAND"
.PP
To execute a single command remotely, the command may be specified by
placing the command and its arguments after any options to \fBmigrate\fR.
If no command is specified, an interactive shell is created.  If the
\fBSHELL\fR environment variable is present, that shell is invoked,
otherwise \fBcsh\fP is invoked.  In any case, the exit status from the
subprocess is returned by \fBmigrate\fR.
.IP "\fB\-E \fI command\fR"
In some circumstances, programs may be invoked with \fBargv[0]\fR
different from the name of the command.  In this case,
the \fB-E\fR option may be used to specify the name of a file to
execute, and the first argument after the option list specifies the
value of \fBargv[0]\fR.   Otherwise, \fBargv[0]\fR is set to the name
of
the command that is invoked.
.SH "MIGRATING A CURRENT PROCESS"
.IP "\fB\-p\fR"
To migrate a process that is already executing, invoke \fBmigrate\fR
with the \fB\-p\fR option, giving the process ID of the process to
migrate (in hex notation).  Each process must be migrated
individually, in separate runs of \fBmigrate\fR.
.SH "OTHER OPTIONS"
.IP "\fB\-b\fR"
The \fB\-b\fR option may be used to enter ``background mode'', in
which \fBmigrate\fP executes a command and returns immediately, printing
the process identifier of the migrated child.  Thus,
.ce 1
\fBmigrate xyzzy&\fP
is different from
.ce 1
\fBmigrate -b xyzzy\fP.
The process identifier for the former case is printed by the
shell, and it corresponds to the \fBmigrate\fP process; while the process
identifier in the latter case corresponds to the migrated child
itself.  In the former case, normal \fBcsh\fP job control may be used
to foreground and background the migrated child, but in the latter
case, the process is not controlled by \fBcsh\fP.
.IP "\fB\-v\fR"
The \fB\-v\fR option may be used to enter ``verbose mode'', in which
case the host selected for migration is printed, or a message that no
host could be selected is printed if the command is executed locally
due to the \fB\-l\fR option.
.IP "\fB\-D\fR"
The \fB\-D\fR option enables ``debug mode'', which causes various
debugging statements to be printed as the program executes.
.SH "SEE ALSO"
migrate, db, xload, pmake, loadavg, csh, ps
.SH FILES
\fB/sprite/admin/data/migInfo\fR - the global migration database file.
.SH KEYWORDS
process migration, load average, uptime, idle time, database, remote execution
.SH BUGS
If a process that is executing remotely is evicted when that
machine is no longer available, the process will continue to execute
locally.  This is nearly completely transparent to the user (\fBps
-m\fR will no longer show the process as migrated).  Even if the host
were not selected as an ``idle host'', the migrated process can be
evicted if the other host goes from being available to being unavailable.
.PP
If another host is selected at random to migrate a process that is already
running, when that process exits the remote host, the remote host will remain
flagged as ``in use'' for a short period of time.  This is because the
\fBmigrate\fR
process cannot conveniently wait for a process that isn't its child.
@


1.7
log
@allow user to specify background priority
@
text
@d1 1
a1 1
' $Header: /sprite/src/cmds/mig/RCS/mig.man,v 1.6 90/02/20 18:27:55 douglis Exp Locker: douglis $ SPRITE (Berkeley)
d3 1
a3 1
.HS MIG cmds
d6 1
a6 1
mig \- Migrate a command to another machine
d8 1
a8 1
\fBmig\fR [\fB\-BbvlD\fR] [[\fB\-h \fIhost\fR] | [\fB\-H \fIhostID\fR]] [\fB\-p \fIprocessID\fR] [(\fB\-E \fIcmd\fR arg0 | \fIcmd\fR) \fIargs ...\fR]
d14 1
a14 1
a command specified by the arguments to the \fBmig\fR program, or an
d29 1
a29 1
is bypassed; this is useful when invoking \fBmig\fR as a ``remote
d42 1
a42 1
placing the command and its arguments after any options to \fBmig\fR.
d46 1
a46 1
subprocess is returned by \fBmig\fR.
d57 4
a60 3
To migrate a process that is already executing, invoke \fBmig\fR with the \fB\-p\fR
option, giving the process ID of the process to migrate (in hex notation).
Each process must be migrated individually, in separate runs of \fBmig\fR.
d64 1
a64 1
which \fBmig\fP executes a command and returns immediately, printing
d67 1
a67 1
\fBmig xyzzy&\fP
d70 1
a70 1
\fBmig -b xyzzy\fP.
d72 1
a72 1
shell, and it corresponds to the \fBmig\fP process; while the process
d86 1
a86 1
mig, db, xload, pmake, loadavg, csh, ps
d101 2
a102 1
flagged as ``in use'' for a short period of time.  This is because the mig
@


1.6
log
@added -b option
@
text
@d1 1
a1 1
' $Header: /sprite/src/cmds/mig.new/RCS/mig.man,v 1.5 89/06/15 22:55:52 douglis Exp Locker: douglis $ SPRITE (Berkeley)
d8 1
a8 1
\fBmig\fR [\fB\-bvlD\fR] [[\fB\-h \fIhost\fR] | [\fB\-H \fIhostID\fR]] [\fB\-p \fIprocessID\fR] [(\fB\-E \fIcmd\fR arg0 | \fIcmd\fR) \fIargs ...\fR]
d17 4
@


1.5
log
@allow hostID instead of hostName, for efficiency
@
text
@d1 1
a1 1
' $Header: /a/newcmds/mig/RCS/mig.man,v 1.4 89/05/04 17:01:10 douglis Exp Locker: douglis $ SPRITE (Berkeley)
d8 1
a8 1
\fBmig\fR [\fB\-vlD\fR] [[\fB\-h \fIhost\fR] | [\fB\-H \fIhostID\fR]] [\fB\-p \fIprocessID\fR] [(\fB\-E \fIcmd\fR arg0 | \fIcmd\fR) \fIargs ...\fR]
d57 15
@


1.4
log
@added capability to separate exec name and argv[0] via -E option.
useful for pmake.
@
text
@d1 1
a1 1
' $Header: /a/newcmds/mig/RCS/mig.man,v 1.3 88/12/30 09:46:52 ouster Exp Locker: douglis $ SPRITE (Berkeley)
d8 1
a8 2
\fBmig\fR [\fB\-vlD\fR] [\fB\-h \fIhost\fR] [\fB\-p \fIprocessID\fR]
[(\fB\-E \fIcmd\fR arg0 | \fIcmd\fR) \fIargs ...\fR]
d18 1
d23 2
a24 1
a host is specified with the \fB\-h\fR option, then the ``in-use'' flag
d26 4
a29 1
login'' facility to execute commands directly on another host.
@


1.3
log
@More format upgrades.
@
text
@d1 1
a1 1
' $Header: /a/newcmds/mig/RCS/mig.man,v 1.2 88/12/22 09:56:27 ouster Exp Locker: ouster $ SPRITE (Berkeley)
d8 2
a9 1
\fBmig\fR [\fB\-vlD\fR] [\fB\-h \fIhost\fR] [\fB\-p \fIprocessID\fR] [\fIcmd ...\fR]
d39 8
@


1.2
log
@*** empty log message ***
@
text
@d1 1
a1 1
' $Header: /a/newcmds/mig/RCS/mig.man,v 1.1 88/11/21 13:29:02 douglis Exp Locker: douglis $ SPRITE (Berkeley)
d8 1
a8 1
\fBmig\fR [\fB-vlD\fR] [\fB-h \fIhost\fR] [\fB-p \fIprocessID\fR] [\fIcmd ...\fR]
d17 1
a17 1
.IP "\fB-h\fR"
d22 1
a22 1
a host is specified with the \fB-h\fR option, then the ``in-use'' flag
d25 1
a25 1
.IP "\fB-l\fR"
d27 2
a28 2
command is not executed unless the \fB-l\fR option is specified, in
which case the command is executed locally.   The ``\fB-l\fR'' option similiarly
d35 1
a35 1
SHELL environment variable is present, that shell is invoked,
d39 2
a40 2
.IP "\fB-p\fR"
To migrate a process that is already executing, invoke mig with the \fB-p\fR
d42 1
a42 1
Each process must be migrated individually, in separate runs of mig.
d44 2
a45 2
.IP "\fB-v\fR"
The \fB-v\fR option may be used to enter ``verbose mode'', in which
d48 3
a50 3
due to the \fB-l\fR option.
.IP "\fB-D\fR"
The \fB-D\fR option enables ``debug mode'', which causes various
@


1.1
log
@Initial revision
@
text
@d1 3
a3 2
' $Header: /sprite/doc/ref/cmds/RCS/loadavg,v 1.2 88/11/16 10:28:41 douglis Exp $ SPRITE (Berkeley)
.TH mig prog
d5 1
a5 1
.NA
d7 2
a8 2
.SY
\fBmig\fR \fI[-vlD]\fR \fI[-h host]\fR \fI[-x cmd ...]\fR
d14 1
a14 1
a command specified by the arguments to the \fImig\fR program, or an
d17 1
a17 1
.IP "-h"
d22 2
a23 2
a host is specified with the \fI-h\fR option, then the ``in-use'' flag
is bypassed; this is useful when invoking \fImig\fR as a ``remote
d25 1
a25 1
.IP "-l"
d27 2
a28 2
command is not executed unless the \fI-l\fR option is specified, in
which case the command is executed locally.   The "-l" option similiarly
d31 12
a42 9
.IP "-x"
By default,
an interactive shell is created.  If the SHELL environment variable is
present, that shell is invoked, otherwise \fIcsh\fP is invoked.
Alternatively, a  command may be specified using the \fI-x\fR option.
This option must be the last option to \fImig\fP specified, because
all subsequent arguments are considered to be a command to invoke.  In
either case, the exit status from the command is returned by
\fImig\fR.
d44 2
a45 2
.IP "-v"
The \fI-v\fR option may be used to enter ``verbose mode'', in which
d48 3
a50 3
due to the \fI-l\fR option.
.IP "-D"
The \fI-D\fR option enables ``debug mode'', which causes various
d53 1
a53 1
Mig, Db, xload, pmake, loadavg, csh, ps
d55 1
a55 2
.IP /sprite/admin/data/migInfo
The global migration database file.
d59 1
a59 1
If a process that is executing remotely is \fBevicted\fR when that
d61 1
a61 1
locally.  This is nearly completely transparent to the user (\fIps
d65 5
@